跳到主要内容

图形

常用变量​

常用数据:
__vm_width           画布宽度
__vm_height          画布高度
__vm_bpp             画布像素位数
__vm_speed_lvl       设备速度级别 (0-100)，硬件速度越高，数越大
__vm_scr_width       物理屏幕宽度
__vm_scr_height      物理屏幕高度
__vm_auto_gen_rom    是否开发环境
颜色:
black             rgb值:000000    
dark_blue         rgb值:1d2b53        
dark_purple       rgb值:7e2553          
dark_green        rgb值:008751         
brown             rgb值:ab5236    
dark_gray         rgb值:5f574f        
light_gray        rgb值:c2c3c7         
white             rgb值:fff1e8    
red               rgb值:ff004d   
orange            rgb值:ffa300     
yellow            rgb值:ffec27     
green             rgb值:00e436    
blue              rgb值:29adff   
indigo            rgb值:83769c     
pink              rgb值:ff77a8   
peach             rgb值:ffccaa    

内存地址:
__vm_GFX          精灵数据地址  
__vm_MAP          地图数据地址  
__vm_FLAGS        精灵标志数据地址    
__vm_MUSIC        音乐数据地址    
__vm_SFX          音效地址  
__vm_USERDATA     用户数据地址       
__vm_CARTDATA     应用存储数据映射地址       
__vm_VRAM         显存地址(对应画布)   
__vm_DRAWSTAT     绘图状态地址       
__vm_HWSTAT       硬件状态地址

clip​

clip(X, Y, W, H, [CLIP_PREVIOUS])

以像素为单位设置剪切矩形。 所有绘图操作将被裁剪到 x, y 处宽度和高度为 w,h 的矩形。

clip() 进行重置。

当 CLIP_PREVIOUS 为 true 时，用旧的裁剪区域裁剪新的裁剪区域。

pset​

pset(X, Y, [COL])

将 x, y 处的像素设置为特定颜色。

如果未指定 COL，则使用当前绘制颜色。

for y=0,127 do
  for x=0,127 do
    pset(x, y, x*x//8)
  end
end

pget​

pget(X, Y)

返回屏幕上 (X, Y) 处像素的颜色。

while true do
  X, Y = rnd(128), rnd(128)
  DX, DY = rnd(4)-2, rnd(4)-2
  pset(X, Y, pget(DX+X, DY+Y))
end

当 X 和 Y 超出范围时，PGET 返回 0。

sget​

sget(X, Y)

sset​

sset(X, Y, [COL])

获取或设置精灵表像素的颜色 (COL)。

当 X 和 Y 超出范围时，sget 返回 0。

fget​

fget(N, [F])

fset​

fset(N, [F], VAL)

获取或设置精灵 N 的标志 F 的值（VAL）。

F 是标志索引 0..7。

VAL 为 TRUE 或者 FALSE。

标志 0..7 的初始状态可在精灵编辑器中设置，因此可用于创建自定义精灵属性。 也可以通过在 MAP() 中提供掩码来仅绘制地图图块的子集。

当省略 F 时，所有标志都被检索/设置为单个位域。

fset(2, 1 | 2 | 8)   -- SETS BITS 0,1 AND 3
fset(2, 4, TRUE)     -- SETS BIT 4
print(fget(2))       -- 27 (1 | 2 | 8 | 16)

gb2312_to_utf8 (version>=6)​

strutf8=gb2312_to_utf8(strgb)

把gb2312编码的字符串转换为utf8编码 print/drawTxt_h 只支持utf8编码

print/drawTxt_h​

print(STR, X, Y, COL, OPT, SIZE, FONT)

print(STR, [COL])

drawTxt_h 是依赖主机类型的打印接口，不同的主机上效果不同。

print 是设备无关的打印接口。

print 支持STR内部的特殊转义(drawTxt_h不支持):

{p0} 是字符[0-9a-f]或者二进制数值

  • "\*{p0}" 把后面一个字符重复p0次. 例如: "\*4A" 打印4个A
  • "\#{p0}" 设置背景色为p0索引
  • "\-{p0}" 水平移动光标 16-p0 个像素
  • "\|{p0}" 垂直移动光标 16-p0 个像素
  • "\+{p0p1}" 水平+垂直移动光标 16-p0 和 16-p1 个像素
  • "\^" 特殊指令前缀
    • "c{p0}" 使用p0索引色清屏幕
    • "g" 移动光标到原始位置
    • "h" 把当前光标位置设定为原始位置
    • "j{p0p1}" 设定当前光标绝对位置为 x+p0*fontwidth, y+p1*lineheight
    • "r{p0}" 设定自动换行宽度为fontwidth*p0个像素
    • "s{p0}" 设定tab宽度为 p0
    • "x{p0} 设定字体字宽为 p0
    • "x{p0} 设定字体行高度为 p0
    • "w" 字体宽度显示加倍
    • "t" 字体高度显示加倍
    • "=" 条带模式显示
    • "p" 字体双倍大小显示
    • ":AABBCCDDEEFFGGHH" 显示8x8自定义字符, 数据为hex格式8字节大小
    • ".ABCDEFGH" 显示8x8自定义字符, 数据为二进制格式8字节大小
    • "-{w/t/=/p}" 取消特定的显示设定
  • "\f{p0}" 改变字体颜色索引为p0
  • "\n" 新行
  • "\r" 光标回到当前行起始位置
  • "\b" 光标向前移动一个字符
  • "\t" 光标移动到下一个制表符

OPT 是打印选项：

  • bit0: 坐标下对齐
  • bit1-2: 对齐方式，1表示右对齐，2表示做中对齐，3表示不绘制(返回宽度) ，注意，print不支持，drawTxt_h生效
  • bit7: 打印后不换行
  • bit8-15: 字间距, 8位整数(ver>=10时可以为负数)

SIZE 是字体大小，如果是不支持的size，就会使用默认大小。

FONT 是字体名，如果不支持会使用默认。

print支持的字体: 英文 8(8x8)，16(8x16)，默认4(4x6)，中文 16(16x16)。

drawTxt_h支持的字体:

ver<10: Colo-PLAY 8,12,20,32,16 (unsc,cjk,phb)，缺省12。

ver>=10: Colo-PLAY 任意 (ascii,mascii,wascii,DIN_NATURE_Bold,gp,dig,vampire)

NatureMiniPro 任意 (default,ascii,mascii,wascii,DIN_NATURE_Bold,gp,dig,vampire)。

font_add (ver>=10)​

font_add(name,size,ttfdata,cache,rbname)

加载自定义truetype字体。

name 字体名字

size 字体大小, 这里填写0(矢量字体指定大小)

ttfdata 字体数据(ttf字体)

cache 允许缓存的字数, nil或者不在允许范围内(1-default)的数都会使用default大小

rbname 缺少字体时使用的字体,nil表示不会滚

return 字体对象 注意,返回字体对象必须保持引用,避免被回收

字体数据是字符串, 由于rom大小限制, 需要裁剪字体文件, 只包含使用到的字符.

例如:

  • symb.txt 把使用到的字符放到一个文本
  • 使用工具 sfnttool.jar 生产只包含symb.txt里面的字符的字体,这样字体会很小

java -jar sfnttool.jar -c ./my_symb.txt ./SourceHanSansCN-Medium.ttf my.ttf

local dig=
#blob ./my.ttf

local font_tt=font_add("my",0,dig,nil,"mascii")

function _update()
    
end

function _draw()
    cls()
    drawTxt_h("12&`34",100,100,red,0,32,"my")
end

font_close (ver>=10)​

font_close(font)

移除自定义的字体

font font_add返回的字体对象

font_shrink (ver>=10)​

font_shrink(global)

清理字体缓存(节约内存)

global true表示清理自定义和全局字体缓存, false表示只清理自定义字体缓存

注意, 使用大字体渲染后,最好调用font_shrink,释放字体缓存,避免过多占用内存

cursor​

cursor(X, Y, [COL])

设置光标位置。

如果指定了 COL，还要设置当前颜色。

color​

color([COL])

设置绘图函数使用的当前颜色。

如果未指定 COL，则当前颜色设置为 light_gray(rgb=#c2c3c7)。

cls​

cls([COL])

清除屏幕并重置剪辑矩形和打印状态。

COL 默认为 0（黑色）。

camera​

camera([X, Y])

为所有绘图操作设置 -x, -y 的屏幕偏移。

camera() 恢复默认状态。

arc​

arc(X, Y, R, ANGLE1, ANGLE2, [COL])

画圆弧, 逆时针从angle1画到angle2 angle 需要在范围内[-180,180], 0 是点[R,0], 90是点[0,-R]

  • version>=4

circ​

circ(X, Y, R, [COL])

circfill​

circfill(X, Y, R, [COL])

在 x,y 处绘制一个半径为 r 的圆或实心圆。

如果 r 为负，则不绘制圆。

oval​

oval(X0, Y0, X1, Y1, [COL])

ovalfill​

ovalfill(X0, Y0, X1, Y1, [COL])

使用给定的边界矩形绘制一个在 x 和 y 上对称的椭圆（椭圆）。

line​

line(X0, Y0, [X1, Y1, [COL]])

从 (X0, Y0) 到 (X1, Y1) 画一条线。

如果未给出 (X1, Y1)，则使用最后绘制的线的末端。

没有参数的 line() 意味着下一次调用 line(X1, Y1) 将只设置终点而不绘制。

cls()
line()
for i=0,6 do
  line(64+cos(i/6)*20, 64+sin(i/6)*20, 8+i)
end

lines​

lines({x0,y0,x1,y1,...}, [COL], [CLOSE]])

根据表里面的坐标，画线段。

CLOSE表示封闭线段(会连线到x0,y0)。

cls()
lines({0,0,15,15,43,43,},red,true)

rect​

rect(X0, Y0, X1, Y1, [COL])

rectfill​

rectfill(X0, Y0, X1, Y1, [COL])

在 (X0, Y0), (X1, Y1) 处绘制一个矩形或填充矩形。

polygonfill​

polygonfill({x0,y0,x1,y1,...}, [COL])

根据表里面的坐标，进行多边形填充，注意表里面至少需要3组点，最多64组点。

trifill​

trifill(x0,y0,x1,y1,x3,y3, [COL])

三角形填充。

pal​

pal(C0, C1, [P])

pal() 将颜色 c0 替换为 c1，用于三个调色板重新映射之一（p 默认为 0）：

0：绘制调色板

绘制调色板会在绘制颜色时重新映射颜色。 例如，通过将第 9 个调色板值设置为 8，可以将橙色花朵精灵绘制为红色花朵：

pal(9,8)     -- 将后续的橙色（颜色 9）像素绘制为红色（颜色 8）
spr(1,70,60) -- 精灵中的任何橙色像素都将被绘制为红色

更改绘制调色板不会影响已经绘制到屏幕上的任何内容。

1：显示调色板

显示调色板在帧末尾显示时会重新映射整个屏幕。 例如，如果您启动程序然后键入 pal(6,14,1)，您可以看到所有灰色（colour 6）文本立即变为粉红色（colour 14），即使它已经被绘制。 这对于淡入/淡出等全屏效果很有用。

2：二级调色板

由 fillp() 用于绘制精灵。 这提供了从单个 4 位颜色索引到两个 4 位颜色索引的映射。

pal() 将所有调色板重置为系统默认值（包括透明度值）。

pal(P) 将特定调色板 (0..2) 重置为系统默认值。

pal(TBL, [P])

当 pal 的第一个参数是表格时，为每个条目分配颜色。 例如，要将颜色 12 和 14 重新映射为红色：

pal({[12]=9, [14]=8})

或者将整个屏幕阴影重新着色为灰色（包括已经绘制的所有内容）：

pal({1,1,5,5,5,6,7,13,6,7,7,6,13,6,7,1}, 1)

因为表索引从 1 开始，所以在这种情况下最后给出颜色 0。

palt​

palt(C, [T])

将颜色索引的透明度设置为 T（布尔值） 通过 spr()、sspr()、map() 和 tline() 实现绘制透明：

palt(8, true) -- 在后续的 SPRITE/TLINE 绘制调用中8号调色透明不绘制

palt() 重置为默认值：除了颜色 0 之外的所有颜色都是不透明的

当 C 是唯一的参数时，它被视为用于设置所有 16 个值的位域。 例如：将颜色 0 和 1 设置为透明：

palt(0xc000)

spr​

spr(N, X, Y, [W, H], [FLIP_X], [FLIP_Y])

在位置 X,Y 绘制精灵 N (0..n)。

W（width）和H（height）都是1，默认为1，表示多少个精灵块。

颜色 0 默认绘制为透明（请参阅 palt() ）。

当 FLIP_X 为 true 时，水平翻转。

当 FLIP_Y 为 true 时，垂直翻转。

sspr​

sspr(SX, SY, SW, SH, DX, DY, [DW, DH], [FLIP_X], [FLIP_Y])

将精灵图像的矩形 (sx, sy, sw, sh) 拉伸到屏幕上的目标矩形 (sx, sy, dw, dh)。 在这两种情况下，x 和 y 值都是矩形左上角的坐标（以像素为单位），宽度为 w、h。

颜色 0 默认绘制为透明（参见 palt() ）。

dw、dh默认为sw、sh。

当 FLIP_X 为 true 时，水平翻转。

当 FLIP_Y 为 true 时，垂直翻转。

tline​

tline(X0, Y0, X1, Y1, MX, MY, MDX, MDY)

从(X0,Y0)到(X1,Y1)画一条纹理线，纹理数据从map的MX,MY获取

  • MDX: 纹理数据X方向的增量,默认1/8
  • MDY: 纹理数据Y方向的增量,默认0
  • statctl(tlmw/tlmh/tlmx/tlmy) 可以控制纹理映射方式

tspr​

tspr(X0, Y0, X1, Y1, SPRX, SPRY, SPRDX, SPRDY)

从(X0,Y0)到(X1,Y1)画一条纹理线，纹理数据从Sprite的SPRX,SPRY获取。

  • SPRDX: 纹理数据X方向的增量，默认1/8
  • SPRDY: 纹理数据Y方向的增量，默认0
  • statctl(tlmw/tlmh) 可以控制纹理映射方式

fillp​

fillp(P)

程序填充图案是一个 4x4 2 色平铺图案，影响以下的绘图函数：circ() circfill() rect() rectfill() polygonfill() trifill() oval() ovalFill() pset() line() lines()。

P 是从最高位开始读取顺序的位域。 要计算所需模式的 P 值，请将位值加在一起：

  .-----------------------.
  |32768|16384| 8192| 4096|
  |-----|-----|-----|-----|
  | 2048| 1024| 512 | 256 |
  |-----|-----|-----|-----|
  | 128 |  64 |  32 |  16 |
  |-----|-----|-----|-----|
  |  8  |  4  |  2  |  1  |
  '-----------------------'

例如，fillp(4+8+64+128+ 256+512+4096+8192) 将创建一个棋盘图案。

默认填充图案为 0，这意味着绘制单一纯色。

要为图案指定第二种颜色，请使用任何颜色参数的高位：

fillp(0b0011010101101000)
circfill(64,64,20, 0x4E) -- brown and pink

其他设置在位 0b0.111 中给出：

0b0.100 透明度

设置此位时，不绘制第二种颜色。

-- 带有透明方块的棋盘
fillp(0b0011001111001100.1)

0b0.010 应用于精灵

设置后，填充图案将使用辅助调色板提供的颜色映射应用于精灵（spr、sspr、map、tline）。

精灵中的每个像素值（在像往常一样应用绘图调色板之后）都被视为二级调色板的索引。 辅助调色板中的每个条目都包含用于呈现填充图案的两种颜色。 例如，要为精灵中的蓝色像素（颜色 12）绘制白色和红色（7 和 8）棋盘图案：

for I=0,15 do pal(I, I+I*16, 2) end  --  所有其他颜色映射到自己
pal(12, 0x87, 2)                     --  在辅助调色板中重新映射颜色 12
 
fillp(0b0011001111001100.01)         --  棋盘调色板，应用于精灵
spr(1, 64,64)                        --  绘制精灵

0b0.001 全局应用二级调色板

设置后，辅助调色板映射也适用于所有尊重填充图案（circfill、line 等）的绘制函数。 这在与 sprite 绘图函数结合使用时非常有用，因此每个 sprite 像素的颜色索引与提供给绘图函数的颜色索引具有相同的含义。

fillp(0b0011001111001100.001)
pal(12, 0x87, 2)
circfill(64,64,20,12)                -- 红白棋盘圈

辅助调色板映射在常规绘制调色板映射之后应用，所以下面也会画一个红白方格的圆圈：

pal(3,12)
circfill(64,64,20,3)

blit​

blit(x,y,opflag,data,linebytes,w,h,bpp,flag,sx,sy,sw,sh)

绘制图像数据块

x,y 绘制的左上角坐标

opflag 绘制策略

  • bit0 1 表示alpha混合绘制(只有32位颜色模式有效)
  • bit1-2 表示x方向的锚点 0:左,1:右,2:中间
  • bit3-4 表示y方向的锚点 0:上,1:下,2:中间

data 图像数据

data可以是特殊数据,此时linebytes,w,h,bpp忽略:

  • "SPR" 表示直接使用sfx图像
  • "SCR" 表示直接使用屏幕

linebytes 每行数据长度

w,h,bpp 图像宽高和每像素位数

flag 图像数据属性

  • bit0 premul数据(32位颜色，预乘alpha)
  • bit1 swap_br (需要交换blue/red数据)
  • bit2 OPAQUE(不透明，禁用alpha)

sx,sy,sw,sh 选取要绘制的图像矩形

rotspr​

rotspr(SX, SY, SW, SH, DX, DY, ANGLE, ZOOMX, ZOOMY)

类似sspr，但是支持旋转角度和缩放。

palrgb​

palrgb(idx,r,g,b,a)

设置调色板颜色，并返回颜色值(此颜色值可以用来作为COL给其他绘图函数使用)。

white=palrgb(14,0xff,0xff,0xff)
circfill(64,64,20,white)

getcolor​

getcolor(r,g,b,a)

返回可用于绘图函数的颜色值。

注意，对于调色板模式，会查找最相近的调色板颜色。

red=getcolor(0xff,0,0)
circfill(64,64,20,red)

qrcode(ver>=11)​

qrcode(str,col,w,x,y)

在x,y位置绘制二维码, 图像宽度w (w小于最小二维码宽度时不会绘制)(图像超出屏幕不绘制) 返回二维码的原始宽度[21,177]

注意, 绘制只会绘制有效像素, 背景色需要事先绘制.

r=qrcode('this is a test',white,177,35,35)

绘制图像数据块

image​

img_load​

img_load(picdata,[bpp],[flag],[gifall])

加载图片数据(png/jpg格式)，如果提供了bpp参数，会转换为对应的图像格式，否则安装系统规格转换。

支持加载gif图片(version>=6)

  • 默认只加载首帧
  • 通过参数gifall可以加载所有帧:gif=img_gif_load(gifdata,nil,nil,true)
  • 多帧会按照Y方向拼接为一个图像
  • 注意加载所有帧图片会大量消耗内存,尽量避免,计算好内存用量

支持加载webp格式(只支持bpp=16 or 32)(version>=12)

返回图像对象img。

img_close​

img_close(img)

立即释放img资源。

img_info​

img_info(img)

返回图像的w,h,bpp,flag。

如果是gif,返回 w,h,bpp,flag,frame_h,delays

  • frame_h: 帧高度
  • delays: 数组,存放每帧演示时间(ms)

img_draw​

img_draw(img,x,y,opflag)

粘贴图像到x,y位置，opflag参考blit的参数。

img_drawex​

img_drawex(img,x,y,opflag,sx,sy,sw,sh)

粘贴图像的特定区域到x,y位置，opflag参考blit的参数。

img_drawrot [version>=12]​

img_drawrot(img, DX, DY, OPFLAG, [SX, SY, SW, SH, ANGLE, ZOOM])

类似rotspr

  • img的bpp格式必须和规格一致
  • OPFLAG 暂时只支持1
  • SX,SY,SW,SH 为img的图像区域, 超出的话不绘制, 默认为整个图像

img_drawzoom [version>=12]​

img_drawzoom(img, DX, DY, DW, DH, [SX, SY, SW, SH, OPFLAG] )

缩放绘制图像到目标大小

  • img的bpp格式必须和规格一致
  • OPFLAG :
    • bit0 : 当前请使用1
    • bit8 : 1 表示x方向镜像
    • bit9 : 1 表示y方向镜像
  • SX,SY,SW,SH 为img的图像区域, 超出的话不绘制, 默认为整个图像

img_drawgif​

img_drawex(img, frameidx, x,y,opflag,sx,sy,sw,sh)

粘贴gif图像帧的特定区域到x,y位置，opflag参考blit的参数。 返回: 当前帧号,需要的延时时间

coloX-16
version 1
__lua__
local tempgif=
#blob 1.gif
local gif=img_load(tempgif,nil,nil,true)
local frmidx=1
local delay=0
function _draw()
    cls(dark_green)
    local _frmidx,_delay=img_drawgif(gif,frmidx,0,0)
    print(string.format("%d,%d,%d",frmidx,_frmidx,_delay),0,0,red,0,16)
    delay=delay+1000/30
    if delay>_delay then
        frmidx=_frmidx+1
        delay=delay-_delay
    end
end

img_gif_load [version>=6]​

img_gif_load(picdata,[bpp])

加载gif图片数据，如果提供了bpp参数，会转换为对应的图像格式，否则按照系统规格转换。 函数会动态渲染需要的帧, 节省内存

返回图像对象img。

img_gif_file [version>=6]​

img_gif_file(filename,[bpp])

加载gif文件，如果提供了bpp参数，会转换为对应的图像格式，否则按照系统规格转换。 函数会动态渲染需要的帧, 节省内存

返回图像对象img。

img_gif_next [version>=6]​

img_gif_next(img)

根据需要更新帧图像

返回nil表示没有更新 返回整数0表示gif动画结束,1表示更新图像了

coloX-16
version 1
__lua__
local tempgif=
#blob 1.gif
local gif=img_gif_load(tempgif)
function _draw()
    cls(dark_green)
    img_gif_next(gif)
    img_draw(gif,0,0)
end

img_loadwebp(version>=12)​

img_loadwebp(picdata,[bpp],[flag],[opt,cropx,cropy,cropw,croph,sw,sh)

加载图片数据(webp格式)，如果提供了bpp参数，会转换为对应的图像格式，否则安装系统规格转换。bpp只能是16 or 32

  • opt: bit0=1 表示使用裁剪区域加载, bit1=1 表示进行缩小(只能缩小)
  • crop[x,y,w,h] 需要加载的区域
  • sw,sh 缩小后的宽高

返回图像对象和原始图像宽高: img,fullwidth,fullheight

rlottie​

rlottie_load​

rlottie_load(key,cont,w,h)

加载rlottie动画数据，key是id(相同id的cont必须相同)，w/h是渲染大小，返回动画对象ani。

rlottie_close​

rlottie_close(ani)

立即释放ani资源。

rlottie_info​

rlottie_info(ani)

返回 当前帧，总帧数，动画帧速，图像宽，图像高。

rlottie_draw​

rlottie_draw(ani,frameidx,x,y)

绘制动画的特定帧到x,y位置。

rlottie_prop​

rlottie_prop(ani,proptype,keypath,v1,v2,v3)

设定动画路径上的属性参数。

rlottie_mark​

rlottie_mark(ani)

以表格方式返回动画区段 {{name,frm_begin,frm_end},...}